RidgeRun GStreamer Analytics Basics
The RidgeRun GStreamer Analytics solution consists of a group of services and GStreamer traces that collect data from devices and centralize it for visualization and control.The solution is split into two main components:
- Agent: Runs on each device (e.g., Jetson boards, Linux hosts) to collect system, process, and pipeline metrics.
- Server: Provides centralized storage databases and dashboards to visualize the collected data.
The architecture diagram and detailed explanation of each component can be found below:
Agent (runs on each monitored device)
The Agent combines two elements: services running on the device and GStreamer tracers that can be enabled to monitor a process. Together, they gather metrics and logs locally and export them to the central server.
Tracers
The tracers are GStreamer plugins loaded directly into the applications you want to monitor. They capture per-process and per-pipeline metrics such as running time, CPU and memory usage, framerate, and bitrate.
A special circular logging tracer manages GStreamer debug logs, allowing controlled buffer size settings, runtime adjustment of log levels, and exposes filtered logs.
Because tracers are part of the GStreamer runtime, they do not require code modifications; any GStreamer-based application can be monitored simply by enabling them.
Services
The services run independently (typically as Docker containers) and are responsible for collecting system-wide metrics, handling log forwarding, and exporting data to the server in standard formats.
The services included in the agent are:
- System Metrics Service: continuously gather system level metrics like CPU, memory, disk IO and network usage.
- Jetson Metrics Service (Jetson only): Captures GPU, codecs, and hardware accelerator utilization.
- Prometheus Exporter: Receives metrics from tracers and system services via a Unix socket (/run/ridgerun-metrics/metrics.sock), exposes them at an HTTP /metrics endpoint, and registers with Consul for discovery. This exporter is the bridge that makes all local metrics data visible to the server.
- Alloy: Tails local filtered GStreamer debug logs (/var/log/ridgerun/) and forwards them to Loki.
- Logger Agent (HTTP): Provides a control interface to set or adjust global and filtered GST_DEBUG levels at runtime, coordinating with the logging tracer through Unix sockets.
Server (centralized)
The Server aggregates and manages all data exported by the Agents. It provides long-term storage, discovery, and visualization layers that make it possible to explore metrics and logs across many devices. Consist of 4 services: Prometheus, Loki, Grafana and Consul:
- Prometheus: Stores time-series metrics collected from Prometheus Exporters running on the agents.
- Loki: Stores logs forwarded by Alloy from each device.
- Grafana: Provides dashboards to visualize metrics and logs, with filters by system, process, and pipeline. It also includes a custom control panel that lets users adjust logger settings (log level, file size) directly from the UI.
- Consul: Handles service discovery so that agents and exporters register automatically. It also supports the custom Grafana panel by exposing the list of active logger tracers and routes the request through the Logger Agent.
How the pieces talk
The data path from devices to dashboards relies on two channels: metrics and logs.
Metrics flow
- Tracers in GStreamer applications and system/Jetson services emit measurements locally.
- These are written in a simple name/labels/value format to a Unix domain socket (/run/ridgerun-metrics/metrics.sock).
- The Prometheus Exporter reads from this socket, tags metrics with a system identifier, and exposes them through an HTTP /metrics endpoint.
- Prometheus on the server collects metrics from this endpoint and stores the data for visualization in Grafana.
Logs flow
- The logging tracer inside each application writes circular log files, for global and filtered debug logs.
- Alloy ships the filtered logs from the device to Loki on the server.
- Logger Agent provides an HTTP interface to adjust log levels at runtime, coordinating changes with tracers over Unix sockets.
Dashboards and control
- Grafana combines the metrics from Prometheus and logs from Loki into dashboards.
- A custom panel integrates with Consul, showing which loggers are active and letting users adjust global or remote debug levels without restarting applications.